<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.13"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Platform Security Architecture — cryptography and keystore interface: Generators</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectalign" style="padding-left: 0.5em;">
   <div id="projectname">Platform Security Architecture — cryptography and keystore interface
   &#160;<span id="projectnumber">Working draft</span>
   </div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.13 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
$(function() {
  initMenu('',true,false,'search.php','Search');
  $(document).ready(function() { init_search(); });
});
</script>
<div id="main-nav"></div>
</div><!-- top -->
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="header">
  <div class="summary">
<a href="#define-members">Macros</a> &#124;
<a href="#typedef-members">Typedefs</a> &#124;
<a href="#func-members">Functions</a>  </div>
  <div class="headertitle">
<div class="title">Generators</div>  </div>
</div><!--header-->
<div class="contents">
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="define-members"></a>
Macros</h2></td></tr>
<tr class="memitem:ga4788b471385fc667876fbd8a0d3fe062"><td class="memItemLeft" align="right" valign="top">#define&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__generators.html#ga4788b471385fc667876fbd8a0d3fe062">PSA_CRYPTO_GENERATOR_INIT</a>&#160;&#160;&#160;{0}</td></tr>
<tr class="separator:ga4788b471385fc667876fbd8a0d3fe062"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="typedef-members"></a>
Typedefs</h2></td></tr>
<tr class="memitem:ga1f894c4fba202ef8e307d72caf489e3b"><td class="memItemLeft" align="right" valign="top">typedef struct psa_crypto_generator_s&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__generators.html#ga1f894c4fba202ef8e307d72caf489e3b">psa_crypto_generator_t</a></td></tr>
<tr class="separator:ga1f894c4fba202ef8e307d72caf489e3b"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="func-members"></a>
Functions</h2></td></tr>
<tr class="memitem:ga7453491e3b440193be2c5dccc2040fd2"><td class="memItemLeft" align="right" valign="top"><a class="el" href="group__basic.html#ga05676e70ba5c6a7565aff3c36677c1f9">psa_status_t</a>&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__generators.html#ga7453491e3b440193be2c5dccc2040fd2">psa_get_generator_capacity</a> (const <a class="el" href="group__generators.html#ga1f894c4fba202ef8e307d72caf489e3b">psa_crypto_generator_t</a> *generator, size_t *capacity)</td></tr>
<tr class="separator:ga7453491e3b440193be2c5dccc2040fd2"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:gab5712ad29b78c2b170e64cc5bcfc1bce"><td class="memItemLeft" align="right" valign="top"><a class="el" href="group__basic.html#ga05676e70ba5c6a7565aff3c36677c1f9">psa_status_t</a>&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__generators.html#gab5712ad29b78c2b170e64cc5bcfc1bce">psa_generator_read</a> (<a class="el" href="group__generators.html#ga1f894c4fba202ef8e307d72caf489e3b">psa_crypto_generator_t</a> *generator, uint8_t *output, size_t output_length)</td></tr>
<tr class="separator:gab5712ad29b78c2b170e64cc5bcfc1bce"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga06c1ba3d989827d909b4b01ffe983beb"><td class="memItemLeft" align="right" valign="top"><a class="el" href="group__basic.html#ga05676e70ba5c6a7565aff3c36677c1f9">psa_status_t</a>&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__generators.html#ga06c1ba3d989827d909b4b01ffe983beb">psa_generator_import_key</a> (<a class="el" href="group__platform.html#gac3da92a6b8a7f0c01dc348f8e0432e4c">psa_key_slot_t</a> key, <a class="el" href="group__crypto__types.html#ga578159487dfc7096cb191b0d2befe628">psa_key_type_t</a> type, size_t bits, <a class="el" href="group__generators.html#ga1f894c4fba202ef8e307d72caf489e3b">psa_crypto_generator_t</a> *generator)</td></tr>
<tr class="separator:ga06c1ba3d989827d909b4b01ffe983beb"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga563ca64537d90368899286b36d8cf7f3"><td class="memItemLeft" align="right" valign="top"><a class="el" href="group__basic.html#ga05676e70ba5c6a7565aff3c36677c1f9">psa_status_t</a>&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__generators.html#ga563ca64537d90368899286b36d8cf7f3">psa_generator_abort</a> (<a class="el" href="group__generators.html#ga1f894c4fba202ef8e307d72caf489e3b">psa_crypto_generator_t</a> *generator)</td></tr>
<tr class="separator:ga563ca64537d90368899286b36d8cf7f3"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table>
<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
<h2 class="groupheader">Macro Definition Documentation</h2>
<a id="ga4788b471385fc667876fbd8a0d3fe062"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga4788b471385fc667876fbd8a0d3fe062">&#9670;&nbsp;</a></span>PSA_CRYPTO_GENERATOR_INIT</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">#define PSA_CRYPTO_GENERATOR_INIT&#160;&#160;&#160;{0}</td>
        </tr>
      </table>
</div><div class="memdoc">
<p>This macro returns a suitable initializer for a generator object of type <a class="el" href="group__generators.html#ga1f894c4fba202ef8e307d72caf489e3b">psa_crypto_generator_t</a>. </p>

</div>
</div>
<h2 class="groupheader">Typedef Documentation</h2>
<a id="ga1f894c4fba202ef8e307d72caf489e3b"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga1f894c4fba202ef8e307d72caf489e3b">&#9670;&nbsp;</a></span>psa_crypto_generator_t</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">typedef struct psa_crypto_generator_s <a class="el" href="group__generators.html#ga1f894c4fba202ef8e307d72caf489e3b">psa_crypto_generator_t</a></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>The type of the state data structure for generators.</p>
<p>Before calling any function on a generator, the application must initialize it by any of the following means:</p><ul>
<li>Set the structure to all-bits-zero, for example: <div class="fragment"><div class="line"><a class="code" href="group__generators.html#ga1f894c4fba202ef8e307d72caf489e3b">psa_crypto_generator_t</a> generator;</div><div class="line">memset(&amp;generator, 0, <span class="keyword">sizeof</span>(generator));</div></div><!-- fragment --></li>
<li>Initialize the structure to logical zero values, for example: <div class="fragment"><div class="line"><a class="code" href="group__generators.html#ga1f894c4fba202ef8e307d72caf489e3b">psa_crypto_generator_t</a> generator = {0};</div></div><!-- fragment --></li>
<li>Initialize the structure to the initializer <a class="el" href="group__generators.html#ga4788b471385fc667876fbd8a0d3fe062">PSA_CRYPTO_GENERATOR_INIT</a>, for example: <div class="fragment"><div class="line"><a class="code" href="group__generators.html#ga1f894c4fba202ef8e307d72caf489e3b">psa_crypto_generator_t</a> generator = <a class="code" href="group__generators.html#ga4788b471385fc667876fbd8a0d3fe062">PSA_CRYPTO_GENERATOR_INIT</a>;</div></div><!-- fragment --></li>
<li>Assign the result of the function psa_crypto_generator_init() to the structure, for example: <div class="fragment"><div class="line"><a class="code" href="group__generators.html#ga1f894c4fba202ef8e307d72caf489e3b">psa_crypto_generator_t</a> generator;</div><div class="line">generator = psa_crypto_generator_init();</div></div><!-- fragment --></li>
</ul>
<p>This is an implementation-defined <code>struct</code>. Applications should not make any assumptions about the content of this structure except as directed by the documentation of a specific implementation. </p>

</div>
</div>
<h2 class="groupheader">Function Documentation</h2>
<a id="ga563ca64537d90368899286b36d8cf7f3"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga563ca64537d90368899286b36d8cf7f3">&#9670;&nbsp;</a></span>psa_generator_abort()</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname"><a class="el" href="group__basic.html#ga05676e70ba5c6a7565aff3c36677c1f9">psa_status_t</a> psa_generator_abort </td>
          <td>(</td>
          <td class="paramtype"><a class="el" href="group__generators.html#ga1f894c4fba202ef8e307d72caf489e3b">psa_crypto_generator_t</a> *&#160;</td>
          <td class="paramname"><em>generator</em></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Abort a generator.</p>
<p>Once a generator has been aborted, its capacity is zero. Aborting a generator frees all associated resources except for the <code>generator</code> structure itself.</p>
<p>This function may be called at any time as long as the generator object has been initialized to <a class="el" href="group__generators.html#ga4788b471385fc667876fbd8a0d3fe062">PSA_CRYPTO_GENERATOR_INIT</a>, to psa_crypto_generator_init() or a zero value. In particular, it is valid to call <a class="el" href="group__generators.html#ga563ca64537d90368899286b36d8cf7f3">psa_generator_abort()</a> twice, or to call <a class="el" href="group__generators.html#ga563ca64537d90368899286b36d8cf7f3">psa_generator_abort()</a> on a generator that has not been set up.</p>
<p>Once aborted, the generator object may be called.</p>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramdir">[in,out]</td><td class="paramname">generator</td><td>The generator to abort.</td></tr>
  </table>
  </dd>
</dl>
<dl class="retval"><dt>Return values</dt><dd>
  <table class="retval">
    <tr><td class="paramname">PSA_SUCCESS</td><td></td></tr>
    <tr><td class="paramname">PSA_ERROR_BAD_STATE</td><td></td></tr>
    <tr><td class="paramname">PSA_ERROR_COMMUNICATION_FAILURE</td><td></td></tr>
    <tr><td class="paramname">PSA_ERROR_HARDWARE_FAILURE</td><td></td></tr>
    <tr><td class="paramname">PSA_ERROR_TAMPERING_DETECTED</td><td></td></tr>
  </table>
  </dd>
</dl>

</div>
</div>
<a id="ga06c1ba3d989827d909b4b01ffe983beb"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga06c1ba3d989827d909b4b01ffe983beb">&#9670;&nbsp;</a></span>psa_generator_import_key()</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname"><a class="el" href="group__basic.html#ga05676e70ba5c6a7565aff3c36677c1f9">psa_status_t</a> psa_generator_import_key </td>
          <td>(</td>
          <td class="paramtype"><a class="el" href="group__platform.html#gac3da92a6b8a7f0c01dc348f8e0432e4c">psa_key_slot_t</a>&#160;</td>
          <td class="paramname"><em>key</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype"><a class="el" href="group__crypto__types.html#ga578159487dfc7096cb191b0d2befe628">psa_key_type_t</a>&#160;</td>
          <td class="paramname"><em>type</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">size_t&#160;</td>
          <td class="paramname"><em>bits</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype"><a class="el" href="group__generators.html#ga1f894c4fba202ef8e307d72caf489e3b">psa_crypto_generator_t</a> *&#160;</td>
          <td class="paramname"><em>generator</em>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Create a symmetric key from data read from a generator.</p>
<p>This function reads a sequence of bytes from a generator and imports these bytes as a key. The data that is read is discarded from the generator. The generator's capacity is decreased by the number of bytes read.</p>
<p>This function is equivalent to calling <a class="el" href="group__generators.html#gab5712ad29b78c2b170e64cc5bcfc1bce">psa_generator_read</a> and passing the resulting output to <a class="el" href="group__key__management.html#gace37363530e2525a2562f07ceec8efb5" title="Import a key in binary format. ">psa_import_key</a>, but if the implementation provides an isolation boundary then the key material is not exposed outside the isolation boundary.</p>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramdir"></td><td class="paramname">key</td><td>Slot where the key will be stored. This must be a valid slot for a key of the chosen type. It must be unoccupied. </td></tr>
    <tr><td class="paramdir"></td><td class="paramname">type</td><td>Key type (a <code>PSA_KEY_TYPE_XXX</code> value). This must be a symmetric key type. </td></tr>
    <tr><td class="paramdir"></td><td class="paramname">bits</td><td>Key size in bits. </td></tr>
    <tr><td class="paramdir">[in,out]</td><td class="paramname">generator</td><td>The generator object to read from.</td></tr>
  </table>
  </dd>
</dl>
<dl class="retval"><dt>Return values</dt><dd>
  <table class="retval">
    <tr><td class="paramname">PSA_SUCCESS</td><td>Success. </td></tr>
    <tr><td class="paramname">PSA_ERROR_INSUFFICIENT_CAPACITY</td><td>There were fewer than <code>output_length</code> bytes in the generator. Note that in this case, no output is written to the output buffer. The generator's capacity is set to 0, thus subsequent calls to this function will not succeed, even with a smaller output buffer. </td></tr>
    <tr><td class="paramname">PSA_ERROR_NOT_SUPPORTED</td><td>The key type or key size is not supported, either by the implementation in general or in this particular slot. </td></tr>
    <tr><td class="paramname">PSA_ERROR_BAD_STATE</td><td></td></tr>
    <tr><td class="paramname">PSA_ERROR_INVALID_ARGUMENT</td><td>The key slot is invalid. </td></tr>
    <tr><td class="paramname">PSA_ERROR_OCCUPIED_SLOT</td><td>There is already a key in the specified slot. </td></tr>
    <tr><td class="paramname">PSA_ERROR_INSUFFICIENT_MEMORY</td><td></td></tr>
    <tr><td class="paramname">PSA_ERROR_INSUFFICIENT_STORAGE</td><td></td></tr>
    <tr><td class="paramname">PSA_ERROR_COMMUNICATION_FAILURE</td><td></td></tr>
    <tr><td class="paramname">PSA_ERROR_HARDWARE_FAILURE</td><td></td></tr>
    <tr><td class="paramname">PSA_ERROR_TAMPERING_DETECTED</td><td></td></tr>
  </table>
  </dd>
</dl>

</div>
</div>
<a id="gab5712ad29b78c2b170e64cc5bcfc1bce"></a>
<h2 class="memtitle"><span class="permalink"><a href="#gab5712ad29b78c2b170e64cc5bcfc1bce">&#9670;&nbsp;</a></span>psa_generator_read()</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname"><a class="el" href="group__basic.html#ga05676e70ba5c6a7565aff3c36677c1f9">psa_status_t</a> psa_generator_read </td>
          <td>(</td>
          <td class="paramtype"><a class="el" href="group__generators.html#ga1f894c4fba202ef8e307d72caf489e3b">psa_crypto_generator_t</a> *&#160;</td>
          <td class="paramname"><em>generator</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">uint8_t *&#160;</td>
          <td class="paramname"><em>output</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">size_t&#160;</td>
          <td class="paramname"><em>output_length</em>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Read some data from a generator.</p>
<p>This function reads and returns a sequence of bytes from a generator. The data that is read is discarded from the generator. The generator's capacity is decreased by the number of bytes read.</p>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramdir">[in,out]</td><td class="paramname">generator</td><td>The generator object to read from. </td></tr>
    <tr><td class="paramdir">[out]</td><td class="paramname">output</td><td>Buffer where the generator output will be written. </td></tr>
    <tr><td class="paramdir"></td><td class="paramname">output_length</td><td>Number of bytes to output.</td></tr>
  </table>
  </dd>
</dl>
<dl class="retval"><dt>Return values</dt><dd>
  <table class="retval">
    <tr><td class="paramname">PSA_SUCCESS</td><td></td></tr>
    <tr><td class="paramname">PSA_ERROR_INSUFFICIENT_CAPACITY</td><td>There were fewer than <code>output_length</code> bytes in the generator. Note that in this case, no output is written to the output buffer. The generator's capacity is set to 0, thus subsequent calls to this function will not succeed, even with a smaller output buffer. </td></tr>
    <tr><td class="paramname">PSA_ERROR_BAD_STATE</td><td></td></tr>
    <tr><td class="paramname">PSA_ERROR_INSUFFICIENT_MEMORY</td><td></td></tr>
    <tr><td class="paramname">PSA_ERROR_COMMUNICATION_FAILURE</td><td></td></tr>
    <tr><td class="paramname">PSA_ERROR_HARDWARE_FAILURE</td><td></td></tr>
    <tr><td class="paramname">PSA_ERROR_TAMPERING_DETECTED</td><td></td></tr>
  </table>
  </dd>
</dl>

</div>
</div>
<a id="ga7453491e3b440193be2c5dccc2040fd2"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga7453491e3b440193be2c5dccc2040fd2">&#9670;&nbsp;</a></span>psa_get_generator_capacity()</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname"><a class="el" href="group__basic.html#ga05676e70ba5c6a7565aff3c36677c1f9">psa_status_t</a> psa_get_generator_capacity </td>
          <td>(</td>
          <td class="paramtype">const <a class="el" href="group__generators.html#ga1f894c4fba202ef8e307d72caf489e3b">psa_crypto_generator_t</a> *&#160;</td>
          <td class="paramname"><em>generator</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">size_t *&#160;</td>
          <td class="paramname"><em>capacity</em>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Retrieve the current capacity of a generator.</p>
<p>The capacity of a generator is the maximum number of bytes that it can return. Reading <em>N</em> bytes from a generator reduces its capacity by <em>N</em>.</p>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramdir">[in]</td><td class="paramname">generator</td><td>The generator to query. </td></tr>
    <tr><td class="paramdir">[out]</td><td class="paramname">capacity</td><td>On success, the capacity of the generator.</td></tr>
  </table>
  </dd>
</dl>
<dl class="retval"><dt>Return values</dt><dd>
  <table class="retval">
    <tr><td class="paramname">PSA_SUCCESS</td><td></td></tr>
    <tr><td class="paramname">PSA_ERROR_BAD_STATE</td><td></td></tr>
    <tr><td class="paramname">PSA_ERROR_COMMUNICATION_FAILURE</td><td></td></tr>
  </table>
  </dd>
</dl>

</div>
</div>
</div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by &#160;<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.13
</small></address>
</body>
</html>
